Skip to content

set_trace_image: position to line a sketch up with the grid - #11

Closed
bularzik wants to merge 2 commits into
thekannen:mainfrom
bularzik:trace-image-offset
Closed

bularzik wants to merge 2 commits into
thekannen:mainfrom
bularzik:trace-image-offset

Conversation

@bularzik

@bularzik bularzik commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem

set_trace_image can scale and centre a reference image, but it can't move it. A sketch whose squares match the map's after scale usually still sits a fraction of a square off. A client traced a sketch at 23 px per square, and the image ended up 0.37 of a square off in x and 0.26 in y, with no way to fix it.

Change

  • set_trace_image gains position: [x, y], in woxels (256 per square): where the image's centre sits. After center it reads exactly the map centre.
    • It sets the position rather than nudging it, so a retried call leaves the image where it is. (The first version of this PR took relative offset_x/offset_y; a retry moved the image twice, so those were dropped after review.)
    • It is applied after center and scale. A later center moves the image back to the map's centre and discards the position, and the docstring says so.
  • The server rejects anything other than two finite numbers. position on its own is a complete call.
  • The bridge's _set_trace_image sets the TraceImage sprite's position. If no image is loaded, it returns an error.
  • The reply gains position, which is where the image sits after the call (whenever an image is loaded).
  • docs/PROTOCOL.md lists the key.

Validation

  • python server/tools/gate.py: all checks passed. That includes server/tests/test_trace_position.py, with 10 tests.
  • Live, on Windows 11 with Dungeondraft 1.2.0.1:
    • Saved and reopened: Dungeondraft writes the position into the map's trace_image block ("position": "Vector2( 2148, 1988 )"). After a full restart of Dungeondraft on that map, the image came back at [2148, 1988].
    • New trace_image UAT group: set a position, repeat it, check that center resets it, then save, open_map, and read it back. It passes.

Docs

The set_trace_image entry in the tool reference needs the position parameter and result field.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thekannen

Copy link
Copy Markdown
Owner

Thanks, Dan. A sketch that sits a fraction of a square off is a real gap, and this is a small, clean change.

Two things before we take it:

  • Does the offset survive a save and reopen? We've been caught before by values that the live node reports but the map file doesn't keep: an object's modulate tint looked set and was gone on reopen. We need a check that the trace image's position is in the saved map and comes back in a fresh Dungeondraft. If it isn't saved, the tool has to say so.
  • The offset is relative, so a retry moves the image twice. Models retry calls. A position: [x, y] that sets where the image sits would be safe to repeat; if you prefer to keep relative offsets, the docstring should warn about repeating them. Also note that center resets the position, so center plus an offset in one call works, but a later center throws the offset away.

How this would land: this repository is the published copy. Development happens in a separate repository, and each release is exported from it here, so merging into main directly would be overwritten by the next export. Changes we accept get ported into the development repository with credit to you, ship in a release, and then this PR is closed with a link to that release.

offset_x/offset_y moved the image by a delta, so a retried call moved it
twice. position=[x, y] sets where the image's centre sits instead, so
repeating it is harmless. It is applied after center and scale, and a later
center puts the image back at the map's centre, as the docstring now says.

Checked live: the position is written to the map file's trace_image block
and comes back in a freshly started Dungeondraft. A trace_image UAT group
covers set, retry, center, and save-and-reopen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bularzik

Copy link
Copy Markdown
Contributor Author

Thanks. Both points are addressed in bbc2fd2.

  • Saved and reopened: yes. Dungeondraft writes the position into the map's trace_image block ("position": "Vector2( 2148, 1988 )"). After a full restart of Dungeondraft on that map, the image came back at [2148, 1988]. A new trace_image UAT group checks the same through save and open_map.
  • Retries: agreed, so offset_x/offset_y are gone. In their place, position: [x, y] sets where the image's centre sits, in woxels; after center it reads exactly the map centre. Repeating the call is harmless, and the UAT case asserts that a retry leaves the image where it was. It is applied after center and scale. The docstring says a later center moves the image back to the map's centre and discards the position, and the UAT case checks that too.

@bularzik bularzik changed the title set_trace_image: offset_x/offset_y to line a sketch up with the grid set_trace_image: position to line a sketch up with the grid Oct 28, 2026
@thekannen

Copy link
Copy Markdown
Owner

Thanks, Dan. Your version is what landed: position only, the loaded-image check, and the trace_image UAT group. We had added a position alongside the offsets; dropping the offsets is simpler and safer, so we took yours instead. It passes live on macOS, including the save and reopen.

One change to the UAT: the reopen now waits 16 s inside the case, as the save round-trip case does. Dungeondraft logs Parameter "ptr" is null a few seconds after a reopen, and in a full run those lines were charged to the next case.

It also saves the map again after clearing the trace, so the file no longer points at the deleted temp image. Separately, loading a trace after a clear in the same Dungeondraft process logs Parameter "p_child" is null once, though the image still shows. That makes the capture group's trace case fail on a second suite run in one process, so run the suite in a fresh one.

These commits are authored by you in the development repository, so you will show as a contributor here when the release lands. This PR stays open until then and closes with a link to that release.

@thekannen

Copy link
Copy Markdown
Owner

This shipped in v1.4.1, together with the other four PRs, so I'm closing it here. Your work landed as its own commit authored by you (2189ce3), so you now appear in this repository's contributors. Thanks again, Dan. The live tests on macOS and Windows, including save and reopen, all passed.

@thekannen thekannen closed this Oct 30, 2026
@bularzik
bularzik deleted the trace-image-offset branch October 31, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants